﻿// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.
// See the LICENSE file in the project root for more information
// 
// Licensed to the Apache Software Foundation (ASF) under one or more
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership.
// The ASF licenses this file to you under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with
// the License. You may obtain a copy of the License at
// 
// http://www.apache.org/licenses/LICENSE-2.0
// 
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// 

using System;
using System.Collections;

using log4net.Util;
using log4net.Core;

namespace log4net.Appender
{
    /// <summary>
    /// Abstract base class implementation of <see cref="IAppender"/> that 
    /// buffers events in a fixed size buffer.
    /// </summary>
    /// <remarks>
    /// <para>
    /// This base class should be used by appenders that need to buffer a 
    /// number of events before logging them.
    /// For example the <see cref="AdoNetAppender"/> 
    /// buffers events and then submits the entire contents of the buffer to 
    /// the underlying database in one go.
    /// </para>
    /// <para>
    /// Subclasses should override the <see cref="M:SendBuffer(LoggingEvent[])"/>
    /// method to deliver the buffered events.
    /// </para>
    /// <para>The BufferingAppenderSkeleton maintains a fixed size cyclic 
    /// buffer of events. The size of the buffer is set using 
    /// the <see cref="BufferSize"/> property.
    /// </para>
    /// <para>A <see cref="ITriggeringEventEvaluator"/> is used to inspect 
    /// each event as it arrives in the appender. If the <see cref="Evaluator"/> 
    /// triggers, then the current buffer is sent immediately 
    /// (see <see cref="M:SendBuffer(LoggingEvent[])"/>). Otherwise the event 
    /// is stored in the buffer. For example, an evaluator can be used to 
    /// deliver the events immediately when an ERROR event arrives.
    /// </para>
    /// <para>
    /// The buffering appender can be configured in a <see cref="Lossy"/> mode. 
    /// By default the appender is NOT lossy. When the buffer is full all 
    /// the buffered events are sent with <see cref="M:SendBuffer(LoggingEvent[])"/>.
    /// If the <see cref="Lossy"/> property is set to <c>true</c> then the 
    /// buffer will not be sent when it is full, and new events arriving 
    /// in the appender will overwrite the oldest event in the buffer. 
    /// In lossy mode the buffer will only be sent when the <see cref="Evaluator"/>
    /// triggers. This can be useful behavior when you need to know about 
    /// ERROR events but not about events with a lower level, configure an 
    /// evaluator that will trigger when an ERROR event arrives, the whole 
    /// buffer will be sent which gives a history of events leading up to
    /// the ERROR event.
    /// </para>
    /// </remarks>
    /// <author>Nicko Cadell</author>
    /// <author>Gert Driesen</author>
    public abstract class BufferingAppenderSkeleton : AppenderSkeleton
    {
        /// <summary>
        /// Initializes a new instance of the <see cref="BufferingAppenderSkeleton" /> class.
        /// </summary>
        /// <remarks>
        /// <para>
        /// Protected default constructor to allow subclassing.
        /// </para>
        /// </remarks>
        protected BufferingAppenderSkeleton() : this(true)
        {
        }

        /// <summary>
        /// Initializes a new instance of the <see cref="BufferingAppenderSkeleton" /> class.
        /// </summary>
        /// <param name="eventMustBeFixed">the events passed through this appender must be
        /// fixed by the time that they arrive in the derived class' <c>SendBuffer</c> method.</param>
        /// <remarks>
        /// <para>
        /// Protected constructor to allow subclassing.
        /// </para>
        /// <para>
        /// The <paramref name="eventMustBeFixed"/> should be set if the subclass
        /// expects the events delivered to be fixed even if the 
        /// <see cref="BufferSize"/> is set to zero, i.e. when no buffering occurs.
        /// </para>
        /// </remarks>
        protected BufferingAppenderSkeleton(bool eventMustBeFixed) : base()
        {
            this.m_eventMustBeFixed = eventMustBeFixed;
        }

        /// <summary>
        /// Gets or sets a value that indicates whether the appender is lossy.
        /// </summary>
        /// <value>
        /// <c>true</c> if the appender is lossy, otherwise <c>false</c>. The default is <c>false</c>.
        /// </value>
        /// <remarks>
        /// <para>
        /// This appender uses a buffer to store logging events before 
        /// delivering them. A triggering event causes the whole buffer
        /// to be send to the remote sink. If the buffer overruns before
        /// a triggering event then logging events could be lost. Set
        /// <see cref="Lossy"/> to <c>false</c> to prevent logging events 
        /// from being lost.
        /// </para>
        /// <para>If <see cref="Lossy"/> is set to <c>true</c> then an
        /// <see cref="Evaluator"/> must be specified.</para>
        /// </remarks>
        public bool Lossy
        {
            get { return this.m_lossy; }
            set { this.m_lossy = value; }
        }

        /// <summary>
        /// Gets or sets the size of the cyclic buffer used to hold the 
        /// logging events.
        /// </summary>
        /// <value>
        /// The size of the cyclic buffer used to hold the logging events.
        /// </value>
        /// <remarks>
        /// <para>
        /// The <see cref="BufferSize"/> option takes a positive integer
        /// representing the maximum number of logging events to collect in 
        /// a cyclic buffer. When the <see cref="BufferSize"/> is reached,
        /// oldest events are deleted as new events are added to the
        /// buffer. By default the size of the cyclic buffer is 512 events.
        /// </para>
        /// <para>
        /// If the <see cref="BufferSize"/> is set to a value less than
        /// or equal to 1 then no buffering will occur. The logging event
        /// will be delivered synchronously (depending on the <see cref="Lossy"/>
        /// and <see cref="Evaluator"/> properties). Otherwise the event will
        /// be buffered.
        /// </para>
        /// </remarks>
        public int BufferSize
        {
            get { return this.m_bufferSize; }
            set { this.m_bufferSize = value; }
        }

        /// <summary>
        /// Gets or sets the <see cref="ITriggeringEventEvaluator"/> that causes the 
        /// buffer to be sent immediately.
        /// </summary>
        /// <value>
        /// The <see cref="ITriggeringEventEvaluator"/> that causes the buffer to be
        /// sent immediately.
        /// </value>
        /// <remarks>
        /// <para>
        /// The evaluator will be called for each event that is appended to this 
        /// appender. If the evaluator triggers then the current buffer will 
        /// immediately be sent (see <see cref="M:SendBuffer(LoggingEvent[])"/>).
        /// </para>
        /// <para>If <see cref="Lossy"/> is set to <c>true</c> then an
        /// <see cref="Evaluator"/> must be specified.</para>
        /// </remarks>
        public ITriggeringEventEvaluator Evaluator
        {
            get { return this.m_evaluator; }
            set	{ this.m_evaluator = value; }
        }

        /// <summary>
        /// Gets or sets the value of the <see cref="ITriggeringEventEvaluator"/> to use.
        /// </summary>
        /// <value>
        /// The value of the <see cref="ITriggeringEventEvaluator"/> to use.
        /// </value>
        /// <remarks>
        /// <para>
        /// The evaluator will be called for each event that is discarded from this 
        /// appender. If the evaluator triggers then the current buffer will immediately 
        /// be sent (see <see cref="M:SendBuffer(LoggingEvent[])"/>).
        /// </para>
        /// </remarks>
        public ITriggeringEventEvaluator LossyEvaluator
        {
            get { return this.m_lossyEvaluator; }
            set	{ this.m_lossyEvaluator = value; }
        }

        /// <summary>
        /// Gets or sets a value indicating if only part of the logging event data
        /// should be fixed.
        /// </summary>
        /// <value>
        /// <c>true</c> if the appender should only fix part of the logging event 
        /// data, otherwise <c>false</c>. The default is <c>false</c>.
        /// </value>
        /// <remarks>
        /// <para>
        /// Setting this property to <c>true</c> will cause only part of the
        /// event data to be fixed and serialized. This will improve performance.
        /// </para>
        /// <para>
        /// See <see cref="M:LoggingEvent.FixVolatileData(FixFlags)"/> for more information.
        /// </para>
        /// </remarks>
        [Obsolete("Use Fix property")]
        public virtual bool OnlyFixPartialEventData
        {
            get { return (this.Fix == FixFlags.Partial); }
            set 
            { 
                if (value)
                {
                    this.Fix = FixFlags.Partial;
                }
                else
                {
                    this.Fix = FixFlags.All;
                }
            }
        }

        /// <summary>
        /// Gets or sets a the fields that will be fixed in the event
        /// </summary>
        /// <value>
        /// The event fields that will be fixed before the event is buffered
        /// </value>
        /// <remarks>
        /// <para>
        /// The logging event needs to have certain thread specific values 
        /// captured before it can be buffered. See <see cref="LoggingEvent.Fix"/>
        /// for details.
        /// </para>
        /// </remarks>
        /// <seealso cref="LoggingEvent.Fix"/>
        public virtual FixFlags Fix
        {
            get { return this.m_fixFlags; }
            set { this.m_fixFlags = value; }
        }

        /// <summary>
        /// Flushes any buffered log data.
        /// </summary>
        /// <param name="millisecondsTimeout">The maximum time to wait for logging events to be flushed.</param>
        /// <returns><c>True</c> if all logging events were flushed successfully, else <c>false</c>.</returns>
        public override bool Flush(int millisecondsTimeout)
        {
            this.Flush();
            return true;
        }

        /// <summary>
        /// Flush the currently buffered events
        /// </summary>
        /// <remarks>
        /// <para>
        /// Flushes any events that have been buffered.
        /// </para>
        /// <para>
        /// If the appender is buffering in <see cref="Lossy"/> mode then the contents
        /// of the buffer will NOT be flushed to the appender.
        /// </para>
        /// </remarks>
        public virtual void Flush()
        {
            this.Flush(false);
        }

        /// <summary>
        /// Flush the currently buffered events
        /// </summary>
        /// <param name="flushLossyBuffer">set to <c>true</c> to flush the buffer of lossy events</param>
        /// <remarks>
        /// <para>
        /// Flushes events that have been buffered. If <paramref name="flushLossyBuffer" /> is
        /// <c>false</c> then events will only be flushed if this buffer is non-lossy mode.
        /// </para>
        /// <para>
        /// If the appender is buffering in <see cref="Lossy"/> mode then the contents
        /// of the buffer will only be flushed if <paramref name="flushLossyBuffer" /> is <c>true</c>.
        /// In this case the contents of the buffer will be tested against the 
        /// <see cref="LossyEvaluator"/> and if triggering will be output. All other buffered
        /// events will be discarded.
        /// </para>
        /// <para>
        /// If <paramref name="flushLossyBuffer" /> is <c>true</c> then the buffer will always
        /// be emptied by calling this method.
        /// </para>
        /// </remarks>
        public virtual void Flush(bool flushLossyBuffer)
        {
            // This method will be called outside of the AppenderSkeleton DoAppend() method
            // therefore it needs to be protected by its own lock. This will block any
            // Appends while the buffer is flushed.
            lock(this)
            {
                if (this.m_cb != null && this.m_cb.Length > 0)
                {
                    if (this.m_lossy)
                    {
                        // If we are allowed to eagerly flush from the lossy buffer
                        if (flushLossyBuffer)
                        {
                            if (this.m_lossyEvaluator != null)
                            {
                                // Test the contents of the buffer against the lossy evaluator
                                LoggingEvent[] bufferedEvents = this.m_cb.PopAll();
                                ArrayList filteredEvents = new ArrayList(bufferedEvents.Length);

                                foreach(LoggingEvent loggingEvent in bufferedEvents)
                                {
                                    if (this.m_lossyEvaluator.IsTriggeringEvent(loggingEvent))
                                    {
                                        filteredEvents.Add(loggingEvent);
                                    }
                                }

                                // Send the events that meet the lossy evaluator criteria
                                if (filteredEvents.Count > 0)
                                {
                                    this.SendBuffer((LoggingEvent[])filteredEvents.ToArray(typeof(LoggingEvent)));
                                }
                            }
                            else
                            {
                                // No lossy evaluator, all buffered events are discarded
                                this.m_cb.Clear();
                            }
                        }
                    }
                    else
                    {
                        // Not lossy, send whole buffer
                        this.SendFromBuffer(null, this.m_cb);
                    }
                }
            }
        }

        /// <summary>
        /// Initialize the appender based on the options set
        /// </summary>
        /// <remarks>
        /// <para>
        /// This is part of the <see cref="IOptionHandler"/> delayed object
        /// activation scheme. The <see cref="ActivateOptions"/> method must 
        /// be called on this object after the configuration properties have
        /// been set. Until <see cref="ActivateOptions"/> is called this
        /// object is in an undefined state and must not be used. 
        /// </para>
        /// <para>
        /// If any of the configuration properties are modified then 
        /// <see cref="ActivateOptions"/> must be called again.
        /// </para>
        /// </remarks>
        public override void ActivateOptions() 
        {
            base.ActivateOptions();

            // If the appender is in Lossy mode then we will
            // only send the buffer when the Evaluator triggers
            // therefore check we have an evaluator.
            if (this.m_lossy && this.m_evaluator == null)
            {
                this.ErrorHandler.Error("Appender [" + this.Name + "] is Lossy but has no Evaluator. The buffer will never be sent!"); 
            }

            if (this.m_bufferSize > 1)
            {
                this.m_cb = new CyclicBuffer(this.m_bufferSize);
            }
            else
            {
                this.m_cb = null;
            }
        }

        /// <summary>
        /// Close this appender instance.
        /// </summary>
        /// <remarks>
        /// <para>
        /// Close this appender instance. If this appender is marked
        /// as not <see cref="Lossy"/> then the remaining events in 
        /// the buffer must be sent when the appender is closed.
        /// </para>
        /// </remarks>
        protected override void OnClose() 
        {
            // Flush the buffer on close
            this.Flush(true);
        }

        /// <summary>
        /// This method is called by the <see cref="M:AppenderSkeleton.DoAppend(LoggingEvent)"/> method. 
        /// </summary>
        /// <param name="loggingEvent">the event to log</param>
        /// <remarks>
        /// <para>
        /// Stores the <paramref name="loggingEvent"/> in the cyclic buffer.
        /// </para>
        /// <para>
        /// The buffer will be sent (i.e. passed to the <see cref="SendBuffer"/> 
        /// method) if one of the following conditions is met:
        /// </para>
        /// <list type="bullet">
        ///         <item>
        ///             <description>The cyclic buffer is full and this appender is
        ///             marked as not lossy (see <see cref="Lossy"/>)</description>
        ///         </item>
        ///         <item>
        ///             <description>An <see cref="Evaluator"/> is set and
        ///             it is triggered for the <paramref name="loggingEvent"/>
        ///             specified.</description>
        ///         </item>
        /// </list>
        /// <para>
        /// Before the event is stored in the buffer it is fixed
        /// (see <see cref="M:LoggingEvent.FixVolatileData(FixFlags)"/>) to ensure that
        /// any data referenced by the event will be valid when the buffer
        /// is processed.
        /// </para>
        /// </remarks>
        protected override void Append(LoggingEvent loggingEvent) 
        {
            // If the buffer size is set to 1 or less then the buffer will be
            // sent immediately because there is not enough space in the buffer
            // to buffer up more than 1 event. Therefore as a special case
            // we don't use the buffer at all.
            if (this.m_cb == null || this.m_bufferSize <= 1)
            {
                // Only send the event if we are in non lossy mode or the event is a triggering event
                if ((!this.m_lossy) || 
                    (this.m_evaluator != null && this.m_evaluator.IsTriggeringEvent(loggingEvent)) || 
                    (this.m_lossyEvaluator != null && this.m_lossyEvaluator.IsTriggeringEvent(loggingEvent)))
                {
                    if (this.m_eventMustBeFixed)
                    {
                        // Derive class expects fixed events
                        loggingEvent.Fix = this.Fix;
                    }

                    // Not buffering events, send immediately
                    this.SendBuffer(new LoggingEvent[] { loggingEvent });
                }
            }
            else
            {
                // Because we are caching the LoggingEvent beyond the
                // lifetime of the Append() method we must fix any
                // volatile data in the event.
                loggingEvent.Fix = this.Fix;

                // Add to the buffer, returns the event discarded from the buffer if there is no space remaining after the append
                LoggingEvent discardedLoggingEvent = this.m_cb.Append(loggingEvent);

                if (discardedLoggingEvent != null)
                {
                    // Buffer is full and has had to discard an event
                    if (!this.m_lossy)
                    {
                        // Not lossy, must send all events
                        this.SendFromBuffer(discardedLoggingEvent, this.m_cb);
                    }
                    else
                    {
                        // Check if the discarded event should not be logged
                        if (this.m_lossyEvaluator == null || !this.m_lossyEvaluator.IsTriggeringEvent(discardedLoggingEvent))
                        {
                            // Clear the discarded event as we should not forward it
                            discardedLoggingEvent = null;
                        }

                        // Check if the event should trigger the whole buffer to be sent
                        if (this.m_evaluator != null && this.m_evaluator.IsTriggeringEvent(loggingEvent))
                        {
                            this.SendFromBuffer(discardedLoggingEvent, this.m_cb);
                        }
                        else if (discardedLoggingEvent != null)
                        {
                            // Just send the discarded event
                            this.SendBuffer(new LoggingEvent[] { discardedLoggingEvent });
                        }
                    }
                }
                else
                {
                    // Buffer is not yet full

                    // Check if the event should trigger the whole buffer to be sent
                    if (this.m_evaluator != null && this.m_evaluator.IsTriggeringEvent(loggingEvent))
                    {
                        this.SendFromBuffer(null, this.m_cb);
                    }
                }
            }
        }

        /// <summary>
        /// Sends the contents of the buffer.
        /// </summary>
        /// <param name="firstLoggingEvent">The first logging event.</param>
        /// <param name="buffer">The buffer containing the events that need to be send.</param>
        /// <remarks>
        /// <para>
        /// The subclass must override <see cref="M:SendBuffer(LoggingEvent[])"/>.
        /// </para>
        /// </remarks>
        protected virtual void SendFromBuffer(LoggingEvent firstLoggingEvent, CyclicBuffer buffer)
        {
            LoggingEvent[] bufferEvents = buffer.PopAll();

            if (firstLoggingEvent == null)
            {
                this.SendBuffer(bufferEvents);
            }
            else if (bufferEvents.Length == 0)
            {
                this.SendBuffer(new LoggingEvent[] { firstLoggingEvent });
            }
            else
            {
                // Create new array with the firstLoggingEvent at the head
                LoggingEvent[] events = new LoggingEvent[bufferEvents.Length + 1];
                Array.Copy(bufferEvents, 0, events, 1, bufferEvents.Length);
                events[0] = firstLoggingEvent;

                this.SendBuffer(events);
            }
        }

        /// <summary>
        /// Sends the events.
        /// </summary>
        /// <param name="events">The events that need to be send.</param>
        /// <remarks>
        /// <para>
        /// The subclass must override this method to process the buffered events.
        /// </para>
        /// </remarks>
        protected abstract void SendBuffer(LoggingEvent[] events);

        /// <summary>
        /// The default buffer size.
        /// </summary>
        /// <remarks>
        /// The default size of the cyclic buffer used to store events.
        /// This is set to 512 by default.
        /// </remarks>
        private const int DEFAULT_BUFFER_SIZE = 512;

        /// <summary>
        /// The size of the cyclic buffer used to hold the logging events.
        /// </summary>
        /// <remarks>
        /// Set to <see cref="DEFAULT_BUFFER_SIZE"/> by default.
        /// </remarks>
        private int m_bufferSize = DEFAULT_BUFFER_SIZE;

        /// <summary>
        /// The cyclic buffer used to store the logging events.
        /// </summary>
        private CyclicBuffer m_cb;

        /// <summary>
        /// The triggering event evaluator that causes the buffer to be sent immediately.
        /// </summary>
        /// <remarks>
        /// The object that is used to determine if an event causes the entire
        /// buffer to be sent immediately. This field can be <c>null</c>, which 
        /// indicates that event triggering is not to be done. The evaluator
        /// can be set using the <see cref="Evaluator"/> property. If this appender
        /// has the <see cref="m_lossy"/> (<see cref="Lossy"/> property) set to 
        /// <c>true</c> then an <see cref="Evaluator"/> must be set.
        /// </remarks>
        private ITriggeringEventEvaluator m_evaluator;

        /// <summary>
        /// Indicates if the appender should overwrite events in the cyclic buffer 
        /// when it becomes full, or if the buffer should be flushed when the 
        /// buffer is full.
        /// </summary>
        /// <remarks>
        /// If this field is set to <c>true</c> then an <see cref="Evaluator"/> must 
        /// be set.
        /// </remarks>
        private bool m_lossy = false;

        /// <summary>
        /// The triggering event evaluator filters discarded events.
        /// </summary>
        /// <remarks>
        /// The object that is used to determine if an event that is discarded should
        /// really be discarded or if it should be sent to the appenders. 
        /// This field can be <c>null</c>, which indicates that all discarded events will
        /// be discarded. 
        /// </remarks>
        private ITriggeringEventEvaluator m_lossyEvaluator;

        /// <summary>
        /// Value indicating which fields in the event should be fixed
        /// </summary>
        /// <remarks>
        /// By default all fields are fixed
        /// </remarks>
        private FixFlags m_fixFlags = FixFlags.All;

        /// <summary>
        /// The events delivered to the subclass must be fixed.
        /// </summary>
        private readonly bool m_eventMustBeFixed;
    }
}
